🎯 Goal

When joining a call, especially the first call after app launch, the UI freezes for approximately 1 second. This creates a poor user experience with an unresponsive interface.

📝 Summary

Root Cause

• setLocalDescription and setRemoteDescription are marked with @MainActor
• The underlying WebRTC implementation performs a blocking network call during these operations
• When called from MainActor context, this noticeably blocks the main thread for ~1-2s depending on network conditions

Instrumentation Graphs

See here there is a 1 second hang in instrumentation:

WebRTC Code Trace

1. setLocalDescription is defined in RTCPeerConnection: https://github.com/GetStream/webrtc/blob/main/sdk/objc/api/peerconnection/RTCPeerConnection.mm#L595-L601
2. _peerConnection is a rtc::scoped_refptr<webrtc::PeerConnectionInterface>, with it's concrete SetLocalDescription defined here: https://github.com/GetStream/webrtc/blob/main/pc/peer_connection.cc#L1494-L1499
3. sdp_handler_ is a SdpOfferAnswerHandler, with it's SetLocalDescription defined here: https://github.com/GetStream/webrtc/blob/main/pc/sdp_offer_answer.cc#L1555-L1580
4. This invokes DoSetLocalDescription (https://github.com/GetStream/webrtc/blob/main/pc/sdp_offer_answer.cc#L1542C24-L1545) which then invokes PushdownTransportDescription (https://github.com/GetStream/webrtc/blob/main/pc/sdp_offer_answer.cc#L1696)
5. PushdownTransportDescription finally calls SetLocalDescription on the transport_controller_s which is a JsepTransportController: https://github.com/GetStream/webrtc/blob/main/pc/sdp_offer_answer.cc#L4909-L4910
6. This finally does a blocking network call: https://github.com/GetStream/webrtc/blob/main/pc/jsep_transport_controller.cc#L77-L100

🛠 Implementation

1. Remove @MainActor from both methods to allow them to run on any thread
2. Add thread-safe queue serialization to prevent race conditions in WebRTC operations

Why Queue Serialization is Necessary

Removing @MainActor alone introduces race conditions when multiple threads access the RTCPeerConnection simultaneously. Manual testing showed:

• Without queue: Video fails to establish ~70% of the time
• With queue: Video establishes reliably 100% of the time

The queue maintains the thread safety that @MainActor provided, but without blocking the main thread.

🧪 Manual Testing Notes

1. Join an existing call from iOS
2. Baseline: 1 second UI freeze, video sometimes fails to establish
3. With fix: No UI freeze, video reliably establishes

Testing Results (10 attempts each):

• Baseline: 1s hang, video issues persist
• @mainactor removed only: No hang, but video only works 3/10 times
• @mainactor removed + queue added: No hang, video works 10/10 times

☑️ Contributor Checklist

• [x ] I have signed the Stream CLA (required)
• [x ] This change follows zero ⚠️ policy (required)
• This change should receive manual QA
• Changelog is updated with client-facing changes
• New code is covered by unit tests
• Comparison screenshots added for visual changes
• Affected documentation updated (tutorial, CMS)